Acorn RISC PD-CD 1

home *** CD-ROM | disk | FTP | other *** search

/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / perl / readmearc < prev

Wrap

Text File | 1991-12-14 | 14.9 KB | 406 lines

Archimedes Perl, Release 1.00 Notes ----------------------------------- This port of the Perl language was produced by Paul Moore, July 1990. I can be reached at: E-Mail: pmoore@cix.compulink.co.uk Mail: 10, Mulberry Rise Firdale Park, Northwich, Cheshire CW8 4UQ I am interested in hearing from any perl users who have found bugs in this implementation of perl. Also, if you have any examples of useful perl scripts, let me know and I will incorporate them into the "Examples" directory (with due credit, of course). This port of perl is based on the Unix version of perl, developed and distributed by Larry Wall (see the Readme file). Unix perl is covered by the Gnu General Public License (see file Copying), and hence this port is also so covered. Note that this distribution omits a lot of Unix specific stuff from the original distribution. If you wish to obtain a copy of the original (unported) distribution, send me a FORMATTED 800k disk and return postage, and I will supply a copy. Note that the distribution is archived using David Pilling's !Spark, version 2.0. If you do not have a suitable extract program (!Spark, or one of the later versions of !SparkPlug), let me know and include an extra disk, and I will supply !SparkPlug also. To recompile perl from the sources, you will need a copy of my "Utils" library of C routines. This is available from most Archimedes BBSs, or the Newcastle server, or (if you are desparate) from me - please send a formatted disk and return postage. You will also require some way of processing the grammar in Y.Perl. I use a port of bison (the Gnu version of Yacc). This is available for the Archimedes from David Pilling, on one of his disks, or from me. Please remember - if you want stuff from me, please send enough disks, and format them in advance. Also, be prepared for a long wait - I am not very reliable when it comes to distributing software! (If you need fast service, a good solution is to send large quantities of money, porsches, or equivalent negotiable goods :-) This version of perl corresponds to Perl 3.0, patch level 44. If you are interested in Perl, and have access to Usenet, I would recommend looking at the comp.lang.perl newsgroup. It has loads of interesting stuff on perl, and the designer, Larry Wall, is a regular contributor. Also available these days is a book on Perl, called "Programming Perl", in the Nutshell Handbook series, published by O'Reilley & Associates. Authors, Larry Wall and Randal L. Schwartz. Archimedes Perl =============== The Archimedes version of perl is mostly identical to the Unix version. The documentation comes in three forms. The standard documentation consists of the troff sources for the reference manual, and is in the four files Perl_man,{1-4}. Also, there is the directory Tex, which contains TeX sources for further documentation. There is RefCard, which is a "Reference Card" for perl (patch level 18, I think), and PerlMan, which is a version of the full perl manual in Gnu "Texinfo" format. This is available via FTP from chem.bu.edu, in directory pub/perl-manual. The version here is the latest I have available (currently, corresponding to patch level 41). For the latter, you need texinfo version 2.10 (from the latest Gnu Emacs) - you may need to fiddle with the file if you are using an earlier version of texinfo. I shall only describe the differences between the standard and Archimedes versions of Perl here. As perl is a general purpose language, with low-level access to system functions, it is clearly the low-level stuff that is the least portable, and hence which has been altered most radically. Omitted from Archimedes perl ---------------------------- All Unix OS access functions. Namely, chmod chown link lstat select utime symlink readlink binmode fcntl fileno flock ioctl pipe chroot fork alarm times umask wait accept bind connect getpeername getsockname getsockopt listen recv send setsockopt shutdown socket socketpair dump endpwent getpwent getpwnam getpwuid setpwent endgrent getgrgid getgrnam getgrent setgrent endhostent gethostbyname gethostent sethostent endnetent getnetbyaddr getnetbyname getnetent setnetent endservent getservbyname getservbyport getservent setservent endprotoent getprotobyname getprotoent setprotoent getprotobynumber getlogin getpgrp getppid getpriority setpgrp setpriority These are not implemented, as there is no Archimedes equivalent. The facility to duplicate a file descriptor, as open(OLDFD,">&FD") is not supported. An attempt has been made to support duplicating STDIN/OUT/ERR, but this does not work reliably, and should not be used. I will attempt to rectify this problem, but RISC OS does not supply a dup() system call, so any solution will be dodgy at best. Also missing, are the "special variables" $$ The process ID of the current perl process $< $> Real and effective User ID $( $) Real and effective Group ID The following "special variables" have been added $< The full pathname of the directory where we started perl $> The full pathname of the current directory These were added as there is no "pwd" command on the Archimedes. The mnemonics in the manual ($< is "where we came from" and $> is "where we have gone to") are still appropriate. The variable $! does not correspond to errno in Archimedes perl, as errno very rarely has a useful value. Instead, the last error from the kernel (_kernel_last_oserror) is stored in $! whenever an OS call returns an error (eg, opening files, deleting files, creating directories, syscall(), etc). The dual nature of $! (returning the error number in a numeric context, and the error message in a string context) is retained. Also missing are the 'N' and 'n' templates from pack/unpack. File tests in Archimedes perl ----------------------------- The file tests -x, -o, -X, -O File is executable or owned -l, -S, -p, -b, -c Special file types -u, -g, -k Setuid, setgid, and "sticky" -M, -C File time stamps are missing. The following have changed meaning -r File is readable -w File is writeable -R File is PUBLICLY readable -W File is PUBLICLY writeable -A File time stamp ("age") (See the Archimedes manuals for the distinction here - unless you are using econet, -R and -W are not very useful). Note that RISC OS only records one time stamp for a file - this is tested using -A. New file test -L File is locked Also, the tests -B and -T are NOT defined on filehandles. Only on file names. Other changes in Archimedes perl -------------------------------- The return value from the stat() function has changed. Be careful of this one when porting Unix perl scripts. The new value is an array of 8 elements, as follows Index Value 0 Basic file type (r0 on return from OS_File) 1 File type for timestamped files 2 Load address 3 Execution address 4 File length 5 File attributes 6 File timestamp (as centisec past 00:00:00 1/1/1900) 7 File timestamp (as seconds past 00:00:00 1/1/1970) Note: Index 0 is 0 for "file not found", 1 for a normal file, and 2 for a directory. Index 5 is a bit set encoding the read/write/locked status of the file (see the Archimedes manuals for more details). Indexes 6 and 7 are the same value, in two different forms. The first is the Archimedes standard "5-byte" time format (all numbers in perl are C doubles, so there is no loss of precision), and the second is the Unix standard format. The mkdir() function does not need a second argument (the file mode, under Unix). Instead, it is a unary operator, like rmdir - for example, mkdir "C"; # Make directory C mkdir("Test"); # Make directory Test Similarly, the syntax of kill() has changed - it takes a single argument which is a signal number or name, and raises that signal. There is no list of process IDs - for example, kill "INT"; # signal ESCAPE kill(4); # also signal ESCAPE (SIGINT is 4) These latter two, particularly mkdir(), are a nuisance when porting, and can cause subtle bugs. I was undecided for a long time as to whether to preserve portability at the expense of a "natural" look to Archimedes users. Finally, however, I decided that I prefer the non-portable, but more natural, form. There are two new pack/unpack template values. These are to make conversion of Archimedes standard times easier. T This takes the next 5 bytes of the string, and converts it to a number as if it were a 5-byte 2's complement integer. This is a suitable conversion if the target string was an Archimedes 5-byte time. A repeat count converts a series of 5-byte numbers. P This treats the next 4 bytes of the target string as a pointer to a string whose length is given in the repeat count. When unpacking, Pn reads EXACTLY n bytes from the string pointed to, into the destination string. This is unlike p1, which will stop at a NULL. As there is no way of ensuring in pack() that the argument is exactly n bytes long, the P template is not accepted in pack(). For example, if $ptr holds a pointer to a 5-byte time (say, from a SWI call), then $time = unpack('P5', $ptr); $time = unpack('T',$time); will get the time value into $time. "File globbing", such as <C.*>, IS supported, but the filename patterns conform to the normal Archimedes standard (* is any number of characters, including 0, and # is any single character). This construct currently requires the program "Glob" to be available in Run$Path. The source for Glob is supplied with perl. Things which DO exist in Archimedes perl ---------------------------------------- The following is a list of things which do exist in Archimedes perl. They are all documented for Unix perl, but are worth mentioning here, because they are slightly less "obvious". 1. Unix names for familiar functions. The following functions exist, and work as expected. The Unix-style names have been retained for compatibility. mkdir *Cdir rmdir *Delete on a directory chdir *Dir unlink *Remove 2. "Standard" facilities unfamiliar on the Archimedes. Pipes have been implemented in Archimedes perl. They are implemented using temporary files, which are put into the directory <Tmp$Dir>, or &.Tmp, or the current directory, whichever of these exists (they are tried in that order). This means that the following perl facilities DO exist * Opening pipes, as open(FH, "Command|") or open(FH, "|Command"). * The 'backtick' operator, `Command`. Note that commands can do IO redirection in one of two forms. The "built-in" OS commands use the standard "Command { < infile > outfile }" form, with a bit of post-processing to convert CR/NL line terminators to NL. Other commands are assumed to support the C v3.0 redirection format, "Command < infile > outfile". Any command which is not built-in and yet does not allow C redirection, can be forced to use OS redirection by adding an initial '%' (which is skipped when executing the command). So, for example, the Acorn utility LibFile, which does not use C redirection, can be opened as a pipe via open(LIB, "%LibFile Lib -l |") Associating databases with associative arrays. This has been implemented using the public domain Gnu dbm package. Unfortunately, while this works, it is presently VERY slow. I am aiming to improve this, but for now I really only see it as being present for completeness' sake. The %SIG associative array works as documented, and can be used to trap Escape, by assigning to $SIG{'INT'}. 3. The syscall() function. Syscall() has been implemented, and gives access to SWI calls. See the file Termio in the Perl library (Lib.Termio) for an example of its use. The calling sequence for syscall() is $regs = syscall(SWI, $r0, $r1, ..., $r9); Here, SWI is the SWI name or number (a string is looked up as a name, and a number is used directly). $r0 ... $r9 are passed to the registers to the SWI call. Only as many as are used need be passed. If $rn is a string, it is passed as a pointer to a 0-terminated string, otherwise it is passed as a number. The result, $regs, is either the null string (if an error occurred, when $! gives the error number/message), or it is a packed string containing the return values of r0-r9. To get the actual registers, simply do ($r0, $r1, ..., $r9) = unpack('I9', $regs); Clearly, in the normal case, a more specific unpack() template would be suitable. Note that, due to Perl's tendency to treat numbers and strings as interchangeable, some care must be taken with parameters. For example, syscall("OS_Write0",$str); can fail, if $str is assigned the string "0" - which may have been converted to numeric zero - as in this case Perl will assume you are passing a number, and set r0 to 0 instead of the address of the supplied string "0". To avoid this, make an explicit string - for example syscall("OS_Write0", $str . ''); is guaranteed to work. This is fairly obscure magic (deliberately invalidating the flag which says that the string has a valid numeric value, and then using the string before perl has a chance to notice that the numeric value is still OK), but works fine. User subroutines ================ Using the "user supplied subroutine" facility, the following functions and variables are available in all Archimedes perl scripts. $Mode The current screen mode. This can be set. $Rows The number of screen rows available. $Cols The number of screen columns available. &osrdch() A single character string, read via OS_ReadC. &oswrch($ch) Writes the character $ch (an integer, which is the ASCII code) using OS_WriteC. Returns 1 for success, undef for failure. &osrdstr($len,$lo,$hi) Reads a string using OS_ReadLine. Uses an internal buffer, $len characters long, to hold the input. $lo and $hi are the lowest and highest ASCII codes accepted (defaults 32 and 255 respectively). Returns the input buffer. &oswrstr($str) Writes $str to the screen. Note that $str may contain control characters, including nulls (for example, &oswrstr("\026\000") changes to mode 0). Returns 1 for success, undef for failure. &fx($op,$x,$y) Performs an OS_Byte call. Returns an integer containing the resulting r1 in its bottom byte, the resulting r2 in its second byte, 1 in its third byte if the carry flag is set, otherwise 0, and 0 in its top byte. Wishlist ======== More special file functions. Maybe settype(type,file...), settime(time,file...), etc. Maybe some more user functions... Final Note ========== Any suggestions for improvement to this port will be most gratefully received (particularly if they include the changes to the code!) I have found perl to be extremely useful for "simple" data manipulating tasks. See, for example, script NL in the Examples directory, which greatly aids the conversion of files from MS-DOS. It is possible to make perl scripts executable by allocating a file type, and putting in your !Boot application (if you have a hard disk), *Set Alias$@RunType_xxx Perl %%0 %%*1 *Set File$Type_xxx Perl The only thing this doesn't do is support command options which are always required, such as -P (preprocess using CC -E). But I don't use this much, anyway. Have fun with perl! Paul Moore.